🏫 API de Turmas e Horários - Documentação Completa

📋 Visão Geral

A API de Turmas e Horários é responsável por toda a gestão de turmas, horários e associações de usuários no sistema CordenaAi. Inclui funcionalidades para gerenciar turmas, criar horários específicos, associar usuários a turmas e horários, além de consultas avançadas para relatórios e dashboards.

🎯 Endpoints Disponíveis

🏫 Turmas - Gestão de Turmas

1. GET /api/turmas

Listar Todas as Turmas

2. GET /api/turmas/{id}

Obter Turma por ID

3. GET /api/turmas/unidade/{unidadeId}

Obter Turmas por Unidade

4. POST /api/turmas

Criar Turma

5. PUT /api/turmas/{id}

Atualizar Turma

6. DELETE /api/turmas/{id}

Excluir Turma

📚 UsuarioTurmas - Gestão de Usuários em Turmas

1. GET /api/usuarioturmas/usuario/{identificador}

Obter Turmas por Usuário

2. GET /api/usuarioturmas/turma/{turmaId}

Obter Usuários por Turma

3. GET /api/usuarioturmas/turma/{turmaId}/papel/{papel}

Obter Usuários por Turma e Papel

4. GET /api/usuarioturmas/{id}

Obter Associação por ID

5. POST /api/usuarioturmas

Criar Associação Usuário-Turma

6. PUT /api/usuarioturmas/{id}

Atualizar Associação

7. DELETE /api/usuarioturmas/{id}

Excluir Associação

⏰ HorarioTurmas - Gestão de Horários de Turmas

1. GET /api/horarioturmas

Obter Todos os Horários

2. GET /api/horarioturmas/turma/{turmaId}

Obter Horários por Turma

3. GET /api/horarioturmas/{id}

Obter Horário por ID

4. POST /api/horarioturmas

Criar Horário

5. PUT /api/horarioturmas/{id}

Atualizar Horário

6. DELETE /api/horarioturmas/{id}

Excluir Horário

🔗 HorarioUsuarios - Gestão de Associações Horário-Usuário

1. GET /api/horariousuarios/horario/{horarioId}

Obter Usuários por Horário

2. GET /api/horariousuarios/usuario/{identificador}

Obter Horários por Usuário

3. GET /api/horariousuarios/{id}

Obter Associação por ID

4. POST /api/horariousuarios

Criar Associação Horário-Usuário

5. PUT /api/horariousuarios/{id}

Atualizar Associação

6. DELETE /api/horariousuarios/{id}

Excluir Associação

🎯 TurmaHorario - Endpoints Específicos de Gestão

1. POST /api/turma/criar-horario

Criar Horário para Turma

2. POST /api/turma/horario/{horarioId}/associar-usuario

Associar Usuário ao Horário

3. GET /api/turma/horario/{id}

Obter Horário Específico

🔧 Modelo de Dados

Turma

{
  "id": 1,
  "nome": "Futsal Infantil (6-8 anos)",
  "unidadeId": 1,
  "unidadeNome": "Unidade Centro",
  "responsavelId": "user-guid-here",
  "responsavelNome": "João Silva",
  "status": 1,
  "dataCadastro": "2025-01-15T10:30:00Z",
  "dataAtualizacao": null
}

UsuarioTurma

{
  "id": 1,
  "usuarioId": "user-guid-here",
  "usuarioNome": "João Silva",
  "turmaId": 1,
  "turmaNome": "Futsal Infantil",
  "papelNaTurma": 1,
  "dataCadastro": "2025-01-15T10:30:00Z",
  "dataAtualizacao": null
}

HorarioTurma

{
  "id": 1,
  "turmaId": 1,
  "turmaNome": "Futsal Infantil",
  "descHorario": "08:30 as 12:30",
  "usuarios": [
    {
      "id": 1,
      "horarioId": 1,
      "horarioDescricao": "08:30 as 12:30",
      "usuarioId": "user-guid-here",
      "usuarioNome": "João Silva",
      "papelId": 1,
      "papelNome": "Professor"
    }
  ]
}

HorarioUsuario

{
  "id": 1,
  "horarioId": 1,
  "horarioDescricao": "08:30 as 12:30",
  "usuarioId": "user-guid-here",
  "usuarioNome": "João Silva",
  "papelId": 1,
  "papelNome": "Professor"
}

🔐 Autenticação e Autorização

Todos os endpoints requerem:

📊 Casos de Uso Principais

1. Gestão de Turmas

POST /api/turmas
Content-Type: application/json
Authorization: Bearer {token}

{
  "nome": "Futsal Infantil (6-8 anos)",
  "unidadeId": 1,
  "responsavelId": "user-guid-here",
  "status": 1
}

2. Associação de Usuários a Turmas

POST /api/usuarioturmas
Content-Type: application/json
Authorization: Bearer {token}

{
  "usuarioId": "user-guid-here",
  "turmaId": 1,
  "papelNaTurma": 1
}

3. Criação de Horários

POST /api/turma/criar-horario
Content-Type: application/json
Authorization: Bearer {token}

{
  "turmaId": 1,
  "descHorario": "08:30 as 12:30"
}

4. Associação de Usuários a Horários

POST /api/turma/horario/1/associar-usuario
Content-Type: application/json
Authorization: Bearer {token}

{
  "usuarioId": "user-guid-here",
  "papelId": 1
}

5. Consulta de Horários por Usuário

GET /api/horariousuarios/usuario/user-guid-here
Authorization: Bearer {token}

6. Consulta de Usuários por Horário

GET /api/horariousuarios/horario/1
Authorization: Bearer {token}

7. Consulta de Turmas por Unidade

GET /api/turmas/unidade/1
Authorization: Bearer {token}

⚠️ Validações e Regras de Negócio

Validações Obrigatórias

Regras de Negócio

🚨 Tratamento de Erros

Códigos de Status HTTP

Formato de Erro

{
  "error": "string",
  "message": "string",
  "details": "string",
  "timestamp": "datetime"
}

📈 Performance e Limitações

Limitações

Otimizações

🔄 Integração com Outros Módulos

Módulos Relacionados

📱 Uso em Aplicações

Web App

Mobile App

🛠️ Manutenção e Monitoramento

Logs Importantes

Métricas Monitoradas

📚 Exemplos Práticos

Fluxo Completo de Criação de Turma com Horários

  1. Criar turma via POST /api/turmas
  2. Criar horários via POST /api/turma/criar-horario
  3. Associar usuários à turma via POST /api/usuarioturmas
  4. Associar usuários aos horários via POST /api/turma/horario/{id}/associar-usuario
  5. Verificar associações via GET /api/horariousuarios/horario/{id}

Fluxo de Consulta de Agenda

  1. Obter usuário por identificador
  2. Buscar turmas via GET /api/usuarioturmas/usuario/{identificador}
  3. Buscar horários via GET /api/horariousuarios/usuario/{identificador}
  4. Filtrar por período no frontend
  5. Exibir agenda formatada

Fluxo de Gestão por Unidade

  1. Listar turmas da unidade via GET /api/turmas/unidade/{unidadeId}
  2. Para cada turma, listar horários via GET /api/horarioturmas/turma/{turmaId}
  3. Para cada horário, listar usuários via GET /api/horariousuarios/horario/{horarioId}
  4. Gerar relatório consolidado

Versão: 1.0
Última Atualização: Outubro de 2025
Responsável: Equipe de Desenvolvimento CordenaAi